\name{APAStyler}
\alias{APAStyler}
\alias{APAStyler-methods}
\alias{APAStyler,lm-method}
\alias{APAStyler,mira-method}
\alias{APAStyler,SEMSummary-method}
\title{This function formats output in APA Style}
\description{
APAStyler is a generic function.  There are methods for \code{lm}, \code{mira}, and \code{SEMSummary} objects right now.  The purpose of this function is to conform to standard rounding, asterisks for significance, etc. guidelines from the APA style manual.  Tables or other output from this function are meant to be cut-and-pasted into a manuscript and (ideally) require minimal editing.
}
\usage{
APAStyler(object, ...)
\S4method{APAStyler}{lm}(object, digits = 2, pdigits, copy = TRUE, ...)
\S4method{APAStyler}{mira}(object, lmobject, digits = 2, pdigits, copy = TRUE, ...)
\S4method{APAStyler}{SEMSummary}(object, digits = 2, cov = c("cov", "cor", "both"), copy = TRUE, ...)
}

\arguments{
\item{object}{The main object to be passed to APAstyler.  The class of this determines the method dispatched.}
\item{digits}{The number of digits to use for rounding.  The default is 2.  This is passed to \code{round} and \code{format} to ensure that the output has \code{digits} decimal places.}
\item{pdigits}{The number of digits to use for p-values (when available).  Because there tends to be fewer p-values than other output and precision can be useful in applications such as meta-analysis, this defaults to \code{digits + 1}, but any integer value may be used.}
\item{copy}{A logical value whether or not the results should be written to the clipboard.  This is for purely for convenience to make pasting into a report or manuscript easy.}
\item{lmobject}{This is optional.  See the \sQuote{details} section for more information.}
\item{cov}{This is optional.  One of "cov", "cor", or "both" determining whether to show the covariance matrix for variables (upper triangle), correlation matrix (upper triangle), or both (covariance in upper, correlation in lower).}
\item{\dots}{Additional arguments passed on to the methods.}
}
\section{Methods}{
\describe{

\item{\code{signature(object = "lm")}}{
This is the method for class \code{lm} objects.  It creates a two column matrix, the first has the coefficient estimates, with asterisks to indicate significance, followed by their standard errors in parentheses.  The second column has the 95\% confidence interval around the estimates.  This is done for each explanatory variable in the model.  Two additional rows are added, one for the \eqn{R^2}{R^2} value and one for the overall model F test.  The form is F(numerator df, denominator df) = F-value, p = p-value.
}

\item{\code{signature(object = "mira")}}{
  This is the method for class \code{mira} objects.  Currently it assumes that the \code{mira} object contains model object of class \code{lm} or \code{glm} (or inheriting from class \code{lm}) fit on the imputed datasets.  Other types of \code{mira} objects will return an error.

  A two column matrix will be returned with the coefficient estimates followed by their standard errors in parentheses, and the 95\% confidence intervals around them in the second column.

  Additionally, if the model objects are class \code{lm}, then an \eqn{R^2}{R^2} value will be added to the table.  If the optional \code{lmobject} argument is \emph{also} non-missing, an F-test and p-value will also be reported (see the \sQuote{details} section).
}

\item{\code{signature(object = "SEMSummary")}}{
  This is the method for class \code{SEMSummary} list objects.  It converts the descriptive statistics into a convenient table form.  By default, the output is copied to the clipboard; however, only the descriptive table, not the information on the coverage.  Note that the separator defaults to tabs when copying to the clipboard.
}}}
\details{
\describe{
  \item{Asterisks}{\sQuote{*} are used to indicate significance using the conventional levels: \sQuote{*} = p < .05, \sQuote{**} = p < .01, \sQuote{***} = p < .001.}
  \item{P-values}{are rounded to \code{pdigits}.  However, if the rounded p-value would return all zeros, then it is simply reported as \dQuote{p < .001} (for \code{pdigits = 3}) with the number of 0s equal to \eqn{pdigits - 1}{pdigits - 1}.}
  \item{lmobject}{For the \code{mira} method, the \code{lmobject} argument can optionally be used to pass an object of class \code{lm} that fits the same model as the ones fit on the imputed dataset, \emph{but} fit on the original dataset.  Because the \pkg{mice} package (where the \code{mira} class comes from) does not have a way to calculate a pooled F value or significance test of the models, and psychologists are so keen on having p-values, this calculates an F value and associated p-value using the pooled \eqn{R^2}{R^2} and the degrees of freedom from the model fit on the original dataset.  While biased, this is a conservative estimate because the degrees of freedom obtained from simply removing all cases with any missing values will always be a lower bound of the pooled degrees of freedom.  It is possible to use \code{APAStyler} on an \code{mira} object without passing anything to the \code{lmobject} argument.  In this case, \code{APAStyler} will simply not return an F test or significance value for the model or \eqn{R^2}{R^2}.  As this may be ill-advised statistically, an appropriate warning is issued.}
}
}
\value{
A character matrix containing the appropriately formatted values.  Also may be called for the side effect of copying the character matrix to the clipboard.
}
% \references{}
\author{Joshua Wiley, \url{http://joshuawiley.com/}}

\examples{
## fit a linear model
m <- lm(mpg ~ hp * wt, data = mtcars)

## APA style output
APAStyler(m, copy = FALSE)

## Change the default rounding (note pdigits changes too)
APAStyler(m, digits = 4, copy = FALSE)

## SEMSummary example
s <- SEMSummary(~ Sepal.Length + Petal.Length + Sepal.Width + Petal.Width, data = iris)
APAStyler(s, copy = FALSE)

\dontrun{
require(mice)

## imputed dataset
imp <- mice(nhanes)

## lm models fit to each imputed dataset
m.imp <- with.mids(imp, lm(chl ~ bmi + hyp))

## lm model fit to original
m <- lm(chl ~ bmi + hyp, data = nhanes)

## APA style output
APAStyler(m.imp, copy = FALSE)

## Demonstrating using the lmobject argument
APAStyler(m.imp, lmobject = m, copy = FALSE)

## Compare those degrees of freedom to
summary(m)
summary(m.imp)
}
}
\keyword{print}
\keyword{methods}
